home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / utilities / file / finf1_155.lha / FInf / finf.man < prev    next >
Encoding:
Text File  |  1994-10-19  |  15.9 KB  |  476 lines
  1.  
  2. File INFo manual
  3. ================
  4.  
  5. File INFo V1.155         by Peter Struijk (peter@dutgs1.tudelft.nl)
  6.  
  7. Introduction
  8. ------------
  9.  
  10. FInf is a very versatile directory listing utility.  It can examine the
  11. contents of files and display a short type description.  In addition to this,
  12. FInf has a whole slew of options that allow you to filter files by type, date,
  13. age, size etc., as well as recursive directory descending, and adjustable
  14. output formatting.  So next to simply listing directories, FInf is extremely
  15. useful for creating hybrid commands that perform functions closely tuned to
  16. your specific needs. 
  17.  
  18.  
  19.  
  20. Command Line Arguments
  21. ----------------------
  22.  
  23. Usage: FInf [dir/...] [-lf=LFORMAT ["%s"]/...] [-nl=NOLINE [prefix]]
  24.   [EXE] [IMP] [DOC] [IFF] [NOI] [-t=TYPE string] [-nt=NOTYPE]
  25.   [-na=NOANSI] [-nh=NOHEAD] [-ho=HEADONLY] [NEWER[EQ] object]
  26.   [OLDER[EQ] object] [MINUS n timeunit] [PLUS n timeunit] [-aq]
  27.   [-d=DIRS] [-f=FILES] [-q=QUICK] [-p=PATH] [-a=ALL] [NOX] [NOC]
  28.   [BLOCK(S)] [DATES] [-lt=LONGTYPE] [SUB string] [SORT] [BATCH]
  29.   [LARGER size] [SMALLER size] [SINCE [n] date] [UPTO [n] date]
  30.  
  31. Arguments surrounded by double-quotes are NOT recognized as keywords, this, or
  32. the use of -?  shortcuts can help you circumvent problems with identically
  33. named files and keywords.  Keywords/switches are case independent.
  34.  
  35. FInf parses its arguments in a left to right order, which may cause keywords
  36. to be overridden by keywords that occur later in the command line.  E.g.
  37. "FInf -nt doc" displays only text files while "FInf doc -nt" will disable file
  38. type checking.
  39.  
  40. Strings or values belonging to a keyword have to be placed directly after this
  41. keyword.  Unexpected strings are assumed to be file- or directory patterns.
  42. This means you can place patterns or keywords anywhere on the command line,
  43. except after keywords expecting a string.  Upto 32 patterns may be specified.
  44.  
  45. You may use the backslash "\" as a fixed escape character; If you enter \n it
  46. will be replaced by a new-line, while \" implements a double-quote.
  47.  
  48. FInf sets a returncode level of 20 (FAIL) on a serious error.
  49. Other returncodes FInf currently sets are:
  50.         0 (OK)    when all went fine.
  51.         5 (WARN)  when no objects (files/dirs) were listed at all.
  52.         7 (WARN)  when a explicitly named object belonging to a keyword was not found.
  53.        10 (ERROR) when a break signal was received.
  54.  
  55. Examples
  56. --------
  57.  
  58. In order to get you started, I'll start with a few examples.  A complete
  59. option reference is given later on.
  60.  
  61. Typing "FInf" without any options will display the files in the current
  62. directory, e.g.
  63.  
  64. EM                         14228 --p-rwed 12-Jul-90 22:47:39 XLIB IMP
  65. TeX                       130344 ----rwed 04-Feb-90 19:29:42 EXECUTABLE
  66. Introduction                1918 ----rwed 21-Jul-90 15:23:12 ASCII TEXT
  67. Read Me                     1532 ----rwed 22-Jul-90 16:31:52 ASCII TEXT
  68. Graph                       4526 ----rwed 01-Jun-90 18:13:47 IFF PIC
  69. Tmp  (dir)
  70. 5 files - 1 directory - 307 blocks - 152548 bytes
  71.  
  72. Typing "FInf doc" will display all text files in the current directory, and
  73. "FInf disk* exe" will show all executables starting with "disk".
  74.  
  75. If you use a shell that supports unnamed pipes and aliases, you can very
  76. easily construct new commands as shown below.  If you do not have unnamed
  77. pipes, you can use the BATCH option, the PIPE:  device or temporary files to
  78. obtain equivalent though less elegant functionality.
  79.  
  80. The BATCH option will cause FInf to output to a temporary file and execute the
  81. contents like a batchfile once it's done.  This will give you the same
  82. functionality as single level unnamed pipes.
  83.  
  84. ------
  85. E=FInf [] noi doc path files lformat " \"%s\"" noline ED | execute
  86. or
  87. E=FInf [] noi doc path files lformat " \"%s\"" noline ED batch
  88.  
  89. This alias will execute the command ED with a list of text files that match
  90. any wildcards you specify.  Typing "E" while in the directory shown above
  91. would have executed the command `Ed "Introduction" "Read Me"'.  Note how
  92. escaping the quote character allows you to put quotes around the produced
  93. filename, thus avoiding problems with filenames that have spaces in them.
  94.  
  95. Do not be deterred by the numerous parameters.  Aliases need to be constructed
  96. only once, and when you are examining the requirements of a new alias, you'll
  97. almost automatically conclude you're in need of certain options.  Chances are
  98. FInf provides them.
  99.  
  100. ------
  101. find=FInf NOTYPE FILES QUICK NOHEAD NOANSI PATH ALL SUB []
  102.  
  103. or abbreviated:
  104.  
  105. find=FInf -nt -f -q -nh -na -p -a SUB []
  106.  
  107. This alias will search your current directory, and all subdirectories for
  108. filenames that contain a string you specify.  You can search any directory by
  109. specifying a directory name *after* the search string.  Very useful for
  110. finding files on your harddrive.  If a matching file is found, the full path
  111. will be displayed.
  112.  
  113.  
  114. ------
  115. FInf *.c Quick Path All | Zoo aI <archive>
  116.  
  117. The I option in Zoo causes it to read filenames from the standard input, and
  118. these are provided by FInf.  This particular example will archive all C source
  119. files in the current directory and its subdirectories.
  120.  
  121. ------
  122. A good general alias proved to be
  123. FIB=FInf -q -nh -na -aq -p []
  124.  
  125. Some other examples (for WShell) include (to test omit the BATCH keyword): 
  126.  
  127. alias readme    LITERAL finf -aq sort noi doc "[]#?read#?" -lf "lg %s" batch
  128. alias doc       LITERAL finf -aq sort noi doc "[]#?(.doc|.man)#?" -lf "lg %s" batch
  129. alias guide     LITERAL finf -aq sort noi doc "[]#?.guide#?" -lf "amigaguide %s" batch
  130. alias seek    LITERAL finf -nt noi -f -q -nh -na -p -a SUB []
  131.  
  132. Example entries for your crontab (Cybercron):
  133.  
  134. #   Throw away old garbage in trashcan(s)
  135. 0    0    *    *    *    FInf WORK:Trashcan REST:Trashcan POOL:Trashcan -p -q -na -nh -lf "*"Delete %s quiet force all*"" UPTO 1 MONTH BATCH
  136. #   Compress manual files
  137. #0    0    *    *    *    FInf MAN: -a -p -q -na -nh -f -aq doc larger 4k -lf "*"XPack >nil: %s method NUKE QUIET*"" BATCH
  138. #   Compress music modules
  139. 0    0    *    *    *    FInf MODS: -a -p -q -na -nh -f -aq larger 32k -lf "*"XPack >nil: %s method SQSH QUIET*"" BATCH
  140.  
  141.  
  142.  
  143. File Type Filtering Options
  144. ---------------------------
  145.  
  146. FInf has a set of command line switches that causes it to display only
  147. specific file types.  Here's a list:
  148.  
  149.  
  150. -t=TYPE <string>
  151.  
  152. When FInf recognizes a file, it is able to print a string describing its type.
  153. The TYPE option allows you to display only those files where the pattern
  154. <string> occurs in this file type description.  This keyword can be used to
  155. select virtuallly any file type or groups of file types just by supplying a
  156. carefully chosen <string>.  Note that the LONGTYPE option causes FInf to
  157. search the extended file type description instead of searching the short
  158. description.
  159.  
  160. List of currently recognized file types:
  161.  
  162. The following list can be generated by "FInf ?" followed by another "?" at the
  163. ":" prompt.  FInf's file type recognition is not by any means complete and
  164. even a bit outdated but serves well to distinguish between major groups of
  165. files like e.g.  executables, text, iff.
  166.  
  167. SHORT         LONG
  168.  
  169. UNREADABLE    "Unable to read"
  170. UNKNOWN       "Unknown type"
  171. FIMP DATA     "FImp data file"
  172. OBJ CODE      "Linkable object code"
  173. TTW PIC       "TTW picture"
  174. PW DATA       "PowerWindows data"
  175. DIMP DATA     "DImp data file"
  176. IFF PIC       "IFF picture"
  177. IFF SOUND     "IFF sound"
  178. IFF SCORE     "IFF score"
  179. IFF TEXT      "IFF text"
  180. IFF DMS       "IFF Deluxe Music score"
  181. IFF ANI       "IFF animation"
  182. IFF S3D       "IFF Sculpt 3D scene"
  183. IFF DLV       "IFF Deluxe Video"
  184. IFF DOC       "IFF document"
  185. IFF FILE      "IFF data file"
  186. ASCII TEXT    "ASCII Text"
  187. OLD IMP       "Old imploded"
  188. NORM IMP      "Normal imploded"
  189. PURE IMP      "Pure imploded"
  190. OVLY IMP      "Overlayed imploded"
  191. XLIB IMP      "Library imploded"
  192. XLIB IMP!     "Short library imploded"
  193. EXECUTABLE    "Executable"
  194. OVERLAYED     "Overlayed executable"
  195. NORM IMP*     "Protected normal imploded"
  196. PURE IMP*     "Protected pure imploded"
  197. OVLY IMP*     "Protected overlayed imploded"
  198. XLIB IMP*     "Protected library imploded"
  199. FONT HDR      "Font header"
  200. WB ICON       "WB icon"
  201. DISK ICON     "WB disk icon"
  202. DRAWER        "WB drawer icon"
  203. TOOL          "WB tool icon"
  204. PROJECT       "WB project icon"
  205. GARBAGE       "WB garbage icon"
  206. DEVS ICON     "WB device icon"
  207. KICK ICON     "WB kick icon"
  208.  
  209.  
  210. In addition to filtering file types with the TYPE option there are a number of
  211. often used types that may be directly specified by keyword.  These are:
  212.  
  213. EXE - Display executable files (except imploded executables).
  214. IMP - Display imploded files and imploded data files.
  215. DOC - Display ASCII text files.
  216. IFF - Display all kinds of IFF files. You may also use the TYPE keyword
  217.       to accomplish further differentation.
  218.  
  219.  
  220.  
  221. Other Filtering Options
  222. -----------------------
  223.  
  224. In addition to type filtering, FInf can also examine other properties with
  225. which to exempt certain files from being displayed:
  226.  
  227.  
  228. NEWEREQ <object>
  229.  
  230. Display only objects which were created after or at the same time as
  231. <object>.
  232.  
  233.  
  234. NEWER <object>
  235.  
  236. Display only objects which were created after <object>.
  237.  
  238. OLDEREQ <object>
  239.  
  240. Display only objects which were created before or at the same time
  241. as <object>.
  242.  
  243.  
  244. OLDER <object>
  245.  
  246. Display only objects which were created before <object>.
  247.  
  248.  
  249. UPTO [n] <date>
  250.  
  251. Display only those objects created UPTO a specified date. UPTO accepts
  252. three formats:
  253.     DD-MMM-YY
  254.     TODAY/YESTERDAY/TOMORROW/MONDAY...SUNDAY/FUTURE
  255.     [n] TICK(S)/SECOND(S)/MINUTE(S)/HOUR(S)/DAY(S)/WEEK(S)/MONTH(S)/YEAR(S)
  256. The integer [n] is optional, default is 1. The latter option is
  257. very handy to cleanup your news directory.
  258. E.g. FInf NEWS: -a -p -lf "Delete %s" UPTO 8 WEEKS BATCH
  259. Make sure your system clock contains the correct time! :-)
  260.  
  261.  
  262. SINCE [n] <date>
  263.  
  264. Display only objects since a specified date. For information on the date
  265. formats see UPTO.
  266.  
  267.  
  268. MINUS <n> <timeunit>
  269.  
  270. Substracts a (fixed) offset from the (run-time) date and time specified by
  271. any SINCE, UPTO, NEWER[EQ] and OLDER[EQ] keywords. The time format is a subset
  272. of the format supported by the SINCE and UPTO keywords:
  273.     <n> TICK(S)/SECOND(S)/MINUTE(S)/HOUR(S)/DAY(S)/WEEK(S)/MONTH(S)/YEAR(S)
  274. The integer <n> is required.
  275. E.g. FInf NEWS: -a -p -lf "Delete %s" OLDER .lastread MINUS 3 days
  276. This deletes all files 3 days older than the date of the .lastread file.
  277.  
  278.  
  279. PLUS <n> <timeunit>
  280.  
  281. Adds a (fixed) offset to the (run-time) date and time specified by any SINCE,
  282. UPTO, NEWER[EQ] and OLDER[EQ] keywords. See MINUS for the time offset format.
  283.  
  284.  
  285. LARGER <integer>
  286.  
  287. Display only files with a size larger than or equal to <integer> bytes.
  288. You can specify kilobytes by adding a 'k' as in:
  289. FInf #? ALL LARGER 100K
  290.  
  291.  
  292. SMALLER <integer>
  293.  
  294. Display only files with a size smaller than or equal to <integer> bytes.
  295. You can specify kilobytes by adding a 'k' as in:
  296. FInf #? SMALLER 10K
  297.  
  298.  
  299. SUB <string>
  300.  
  301. Display only objects containing at least one occurance of <string> in their
  302. objectname.
  303.  
  304.  
  305. NOI
  306.  
  307. Do not display .info files.
  308.  
  309.  
  310. -d=DIRS
  311.  
  312. Display directories only.
  313.  
  314.  
  315. -f=FILES
  316.  
  317. Display only files.
  318.  
  319.  
  320. -a=ALL
  321.  
  322. Recursively displays the contents of any subdirectories in addition to
  323. the files/dirs in the current directory.  Wildcards in the path description
  324. are not supported (yet), so for now this option will cause FInf to
  325. recursively enter ALL encountered directories.
  326.  
  327.  
  328.  
  329. Formatting Options
  330. ------------------
  331.  
  332. These switches and keywords control the way in which FInf generates its
  333. output:
  334.  
  335.  
  336. BATCH
  337.  
  338. This will capture FInf's output into a uniquely named temporary file in the T:
  339. directory, and subsequently will execute the file as a batch file that will be
  340. deleted after completion.  This option is handy if you don't have unnamed
  341. pipes.
  342.  
  343.  
  344. BLOCK=BLOCKS
  345.  
  346. This switch will cause FInf to display the number of blocks files occupy on
  347. disk instead of their lengths.  Note that for devices using the fast filing
  348. system, this value will include any extension blocks.
  349.  
  350.  
  351. DATES
  352.  
  353. This will cause FInf to print absolute dates instead of dates with "Yesterday"
  354. of "Sunday" in them.
  355.  
  356.  
  357. -lt=LONGTYPE
  358.  
  359. If specified, FInf will generate listings with a more verbose type
  360. description.  In order to create printing space for this, the date and
  361. protection flags will not be displayed.
  362.  
  363.  
  364. -nt=NOTYPE
  365.  
  366. If you use this switch, the contents of files will not be examined.  The type
  367. description will therefore not be displayed.  The EXE, IMP, DOC, IFF etc.
  368. filters won't work if NOTYPE is set.  NOTYPE will cause FInf to operate about
  369. twice as fast because of the decreased amount of work it has to do for each
  370. file.
  371.  
  372.  
  373. -na=NOANSI
  374.  
  375. This surpresses the generation of ANSI codes used by FInf to select bold or
  376. italic font styles in the footer and such.
  377.  
  378.  
  379. -nh=NOHEAD
  380.  
  381. Like with the normal List command, NoHead will stop FInf from generating
  382. headers/footers with additional information on the examined files.
  383.  
  384.  
  385. -ho=HEADONLY
  386.  
  387. This option is included to quickly simulate the unix DU command.  DU stands
  388. for Directory Usage, an example alias:  du = finf -ho -a []
  389.  
  390.  
  391. NOX
  392.  
  393. This option removes extensions from the filenames.  This might be handy when
  394. you only wish to pass the filename root into the LFormat output.  E.g.  FInf
  395. *.twiddle NOX LFormat "Rename %s.twiddle %s.twaddle" | execute changes all
  396. .twiddle extensions into .twaddle extensions.
  397.  
  398.  
  399. NOC
  400.  
  401. This simple option tells FInf to NOT print any filenotes (comments) which
  402. might be attached to a file or directory.  Note that when the QUICK option is
  403. in effect filenotes are already been ignored.
  404.  
  405.  
  406. -q=QUICK
  407.  
  408. In quick mode, FInf will display only filenames and any paths.  No lengths,
  409. flags, dates, comments or types will be printed, the type filter switches will
  410. still function though.  These bare (path+)file names can be more readily used
  411. by programs you intend to feed FInf's output to.
  412.  
  413.  
  414. -p=PATH
  415.  
  416. If set, a full path will be pasted in front of any displayed filenames.  This
  417. option is useful e.g.  in conjunction with the LFormat or ALL switches.
  418.  
  419.  
  420. -lf=LFORMAT <"...%s...%s...">
  421.  
  422. Works like List's LFormat option.  Briefly, you can specify a string with a
  423. "%s" in it (up to 8 %s expansions are supported), and where FInf normally
  424. would have printed paths+file names, it displays the given string with the
  425. path + file at the %s location.  Useful for pasting commands in front of
  426. filenames so you can pipe the output of FInf to a batchfile, or directly to
  427. execute (if your shell supports this).  E.g.  FInf LFORMAT "rename \"%s\"
  428. \"%s.doc\"" FILES DOC BATCH will append a ".doc" extension to all ASCII files
  429. found.
  430.  
  431.  
  432. -nl=NOLINE [prefix]
  433.  
  434. This causes FInf not to print linefeeds between filenames.  If you use this
  435. together with a LFormat " %s" and a QUICK switch, you'll get a line with file
  436. names separated by spaces.  In the prefix position you may optionally specify
  437. a string to be pasted in front of this line.  This will probably be the name
  438. of a command which requires a list of filenames as its parameters.  Note that
  439. this line will only be printed if any filenames matching your wildcard
  440. specification were found.  E.g.  FInf NOLINE "Ed " LFORMAT "\"%s\" " PATH
  441. FILES will produce something like:  Ed "ram:file1" "ram:doc1" "ram:readme"
  442.  
  443.  
  444. SORT
  445.  
  446. At last, this one sorts the filenames before printing. It didn't require
  447. a rewrite BUT only because this option also enables the NOANSI, NOHEADER
  448. and QUICK keywords. (-na -nh -q), making it less useful for normal
  449. interactive usage. It's primary intended for BATCH jobs.
  450.  
  451.  
  452. -aq
  453.  
  454. This stands for AddQuotes and does just that, it places quotes (") around
  455. all object names. This saves some problems with escaping "'s in aliasses
  456. or simplifies complicated one liners...
  457.  
  458.  
  459. General Information
  460. -------------------
  461.  
  462. This program is Freely-Distributable, as opposed to Public Domain.  Permission
  463. is given to freely distribute this program provided you include this
  464. documentation and any other related files, and no fee is charged in excess of
  465. reasonable media and mailing costs.
  466.  
  467. Currently FInf supports the #,?  and * wild cards.  OS 2.0 wildcarding is used
  468. automatically.  If, during normal operation, there is only one file matching
  469. the file/wildcard specification, and if it is a program file, some additional
  470. information about the number of hunks and the memory usage will be displayed.
  471.  
  472. FInf is pure and can be made resident.
  473.  
  474. Peter Struijk 
  475. (dutgs1@dutgs1.twi.tudelft.nl)
  476.